home *** CD-ROM | disk | FTP | other *** search
/ Archive Magazine CD 1995 / Archive Magazine CD 1995.iso / discs / prog_disc / volume_8 / issue_06 / risc_os / Wimp / SprExtend < prev    next >
Encoding:
Text File  |  1988-12-06  |  7.6 KB  |  211 lines
  1. > Wimp.SprExtend
  2.  
  3. New Calls
  4. ---------
  5.  
  6.         OS_SpriteOp codes 35,36, 50,51,52,53, 60,61
  7.                 SpriteReason_AppendSprite
  8.                 SpriteReason_SetPointerShape
  9.                 SpriteReason_PlotMaskScaled
  10.                 SpriteReason_PaintCharScaled
  11.                 SpriteReason_PutSpriteScaled
  12.                 SpriteReason_PutSpriteGreyScaled
  13.                 SpriteReason_SwitchOutputToSprite
  14.                 SpriteReason_SwitchOutputToMask
  15.         OS_ReadVduBlockSize
  16.  
  17.  
  18. Introduction
  19. ------------
  20.  
  21. The Arthur sprite extension module is available as an upgrade to the Arthur
  22. 1.20 operating system, providing some extra reason codes to SWI OS_SpriteOp. 
  23. The module is provided as standard in the Arthur 2.00 ROM, and the kernel
  24. also supports calls to redirect VDU output into sprites.
  25.  
  26. The extra sprite operations allow arbitrary scaling and colour translation:
  27. they are used by the Wimp to implement mode-independence, and by bit-mapped
  28. printer drivers to cope with the fact that printers have a different pixel
  29. resolution from the screen.
  30.  
  31.  
  32. Installation
  33. ------------
  34.  
  35. To install the sprite extension module, simply *RMLoad it (if it is held in
  36. the library, then *SprExtend will do.
  37.  
  38.                        ***************************
  39.   Due to the way in which the sprite vector is intercepted, the sprite
  40.   extension module must be loaded before the printer driver (if any).
  41.                        ***************************
  42.  
  43.  
  44. The SWI interface
  45. -----------------
  46.  
  47. As with all sprite operations, the extra operations implemented in the sprite
  48. extension module are accessed via SWI OS_SpriteOp.  The extra reason codes
  49. are:
  50.  
  51.         35      AppendSprite
  52.         36      SetPointerShape
  53.  
  54.         50      PlotMaskScaled
  55.         51      PaintCharScaled
  56.         52      PutSpriteScaled
  57.         53      PutSpriteGreyScaled
  58.  
  59.         60      SwitchOutputToSprite
  60.         61      SwitchOutputToMask
  61.  
  62. A short explanation of what the operations do is given below:
  63.  
  64.  
  65. 35 AppendSprite
  66. ---------------
  67.  
  68. Entry:  R0 = reason code
  69.         R1 = areaCBptr
  70.         R2 = name/ptr of 1st sprite
  71.         R3 = name/ptr of 2nd sprite
  72.         R4 = flags (0 ==> merge horizontally, else vertically)
  73. Exit:   1st sprite is result of merging both
  74.         2nd sprite is deleted
  75.         scratch space used (no extra memory apart from that)
  76.  
  77. This call can be used to merge two sprites into one, tacking them together
  78. vertically or horizontally.  It does not use any extra memory, so is useful
  79. if memory is tight!
  80.  
  81.  
  82. 36 SetPointerShape
  83. ------------------
  84.  
  85. Entry:  R1 --> sprite area
  86.         R2 --> sprite name/address
  87.         R3 bits 0..3 = pointer shape number (1..4)
  88.         R3 bit 4 set => don't bother to set the pointer shape data
  89.         R3 bit 5 set => don't bother to set the palette from the sprite
  90.         R3 bit 6 set => don't bother to program the pointer shape number
  91.         R4,R5 = coordinates of active point (pixels from top-left)
  92.         R6 --> factors
  93.         R6 <= 0 ==> use default, depending on screen mode
  94.         R7 --> pixel translation table (target = 2 bpp)
  95.         R7 <= 0 ==> no translation
  96.                (See 'PutSpriteScaled' below for a description
  97.                 of the format of a pixel translation table)
  98.  
  99. This call allows any of the hardware pointer shapes to be programmed from a
  100. sprite, with some degree of mode-independence (ie. the aspect ratio is
  101. catered for).
  102.  
  103. Note that in hi-res mono modes, the pointer shape resolution is 4 times worse
  104. horizontally than the pixel resolution, and that only colours 0,1 and 3 can
  105. be used in the pointer shape definition.  The SpriteExtend call caters for
  106. the resolution problem by halving the width of the pointer, so that it is
  107. still possible to see what it is, although the pointer will be twice as wide
  108. as usual.
  109.  
  110. Bits 4,5 and 6 of R3 can be used to defer certain aspects of this call until
  111. later: for example, if one wanted to set up the pointer shape data without
  112. displaying the pointer, one could set bits 5 and 6 to avoid programming the
  113. palette and pointer shape number.
  114.  
  115. Note that if the sprite is given a translation table, SpriteExtend will
  116. search the table to find out which colours were mapped onto colours 1,2 and 3
  117. in the pointer, and will set the palette entries from those colours.
  118.  
  119. If the sprite has no palette, the palette setting code is not done, and no
  120. error is reported.
  121.  
  122.  
  123. 50 PlotMaskScaled
  124. -----------------
  125.  
  126. Entry:  R0 = &132 or &232 (as appropriate)
  127.         R1 = areaCBptr
  128.         R2 --> sprite name / sprite header (depends on R0)
  129.         R3,R4 = coords to plot sprite at
  130.         R6 --> scale factors (x-mag, y-mag, x-div, y-div)
  131.         R6 <= 0 ==> no scaling
  132.  
  133. An area of the screen corresponding to the 'solid' pixels in the sprite mask
  134. (scaled appropriately) is painted using the current graphics background
  135. colour and action.  If this is an ecf pattern, the pattern is not scaled up.
  136.  
  137.  
  138. 51 PaintCharScaled
  139. ------------------
  140.  
  141. Entry:  R0 = &133 or &233
  142.         R1 = character code
  143.         R3,R4 = coords to paint character at
  144.         R6 --> scale factors (x-mag, y-mag, x-div, y-div)
  145.  
  146. The specified character is painted on the screen with its lower-left corner
  147. at the coordinate specified in R3,R4, using the current graphics foreground
  148. colour and action.
  149.  
  150.  
  151. 52 PutSpriteScaled
  152. ------------------
  153.  
  154. Entry:  R0 = &134 or &234
  155.         R1 = areaCBptr
  156.         R2 --> sprite name/header
  157.         R3,R4 = coords to plot sprite at
  158.         R5 = gcol action
  159.         R6 --> scale factors (x-mag, y-mag, x-div, y-div)
  160.         R6 <= 0 ==> no scaling
  161.         R7 --> pixel translation table (byte array)
  162.         R7 <= 0 ==> no translation
  163.  
  164. The sprite is plotted at the coordinate specified in R3,R4 using the gcol
  165. action in R5, scaled by the factors pointed to by R6 and the pixels transated
  166. using the table pointed to by R7.
  167.  
  168. If bit 3 of R5 is set, then the sprite's mask is used, otherwise not.
  169.  
  170. If R6>0 then the sprite is scaled by the specified amount, otherwise it is
  171. not scaled (ie. the scaling is taken to be 1:1).
  172.  
  173. If R7>0 then the pixels are translated according to the byte array pointed to
  174. by R7.  This table allows the sprite to be plotted (for instance) in a mode
  175. with a different number of bits per pixel than that for the mode in which the
  176. sprite is defined.  In 256-colour modes, the format of the pixels is taken to
  177. be that which relates to the actual screen, rather than the colour/tint
  178. values used for GCOL n,c.  Note that the error 'Bad translation table' is
  179. returned if the translation supplied (or not supplied) means that the output
  180. pixel values are too big for the number of bits per output pixel.
  181.  
  182.  
  183. 53 PutSpriteGreyScaled
  184. ----------------------
  185.  
  186. Entry:  R0 = &135 or &235
  187.         R1 = areaCBptr
  188.         R2 --> sprite name/header
  189.         R3,R4 = coords to plot sprite at
  190.         R5 = gcol action (not implemented - 0 assumed)
  191.         R6 --> scale factors (x-mag, y-mag, x-div, y-div)
  192.         R6 <= 0 ==> no scaling
  193.         R7 --> pixel translation table
  194.         R7 <= 0 ==> no translation
  195.  
  196. This operation is similar to PutSpriteScaled, except that it performs
  197. anti-aliasing on the sprite as it scales it, in the same way as the Font
  198. Manager scales its character definitions.  This means that the sprite used
  199. must have been defined in a mode with 4 bits per pixel, and the pixels
  200. must reflect a linear grey scale (as with anti-aliased font definitions).
  201.  
  202. PutSpriteGreyScaled is considerably slower than PutSpriteScaled, and should
  203. only really be used when the quality of the image is of the utmost
  204. importance.  To speed up the redrawing of an anti-aliased image, it is
  205. possible to draw the image into another sprite (using the Arthur 2.00
  206. SwitchOutputToSprite call), which can then be redrawn more rapidly.
  207.  
  208.  
  209. The OS_SpriteOp calls 60, 61 and 62 are implemented in the Arthur 2.00 kernel
  210. and are documented in "VDU output to sprites/1"
  211.